Description

Backports the wrapper caching fix (#1097 for Maven, #1098 for Gradle) to the v5 release line, so the majority of users who pin actions/setup-java@v5 get the reliability improvement without waiting for the next major (main is already at 6.0.0).

Why

The Maven wrapper distribution (~/.m2/wrapper/dists) and Gradle wrapper distribution (~/.gradle/wrapper) were cached in the same entry as the dependency cache, keyed on the volatile dependency-file hashes (**/pom.xml, **/*.gradle*). Since those files change constantly and there are intentionally no restoreKeys fallbacks (#269), nearly every dependency change was a full cache miss, forcing ./mvnw / ./gradlew to re-download the build tool distribution and hitting the intermittent rate-limit failures reported in #1095.

Approach

Each wrapper distribution now lives in its own additional cache entry keyed only on the rarely-changing wrapper properties file:

• Maven: ~/.m2/wrapper/dists keyed on **/.mvn/wrapper/maven-wrapper.properties
• Gradle: ~/.gradle/wrapper keyed on **/gradle-wrapper.properties

so the distribution survives the frequent dependency-file changes that rotate the main cache key. Optional-cache saves swallow ValidationError and ReserveCacheError, so a project without a wrapper never fails the post step. Main-cache outputs (cache-hit, cache-primary-key) are unchanged for backward compatibility.

Notes for reviewers

• This is a backport, so it is limited to src/cache.ts, __tests__/cache.test.ts, the README caching notes, and the rebuilt dist/. The docs/advanced-usage.md changes from main were intentionally omitted because they anchor to a caching-completeness section that does not exist on the v5 branch.
• The tests were rewritten to match the v5 test harness (jest.spyOn + STATE_*-backed getState), which differs from main.
• First run after upgrade repopulates the new wrapper cache entry (one extra download); old shared-key caches are harmless and age out.
• All 895 tests pass; format-check and lint are clean; dist/ rebuilt.

Fixes: #1095